package cn.featherfly.servlet;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.util.Enumeration;
import java.util.Locale;
import java.util.Map;

/**
 * Defines an object to provide client request information to a servlet. The
 * servlet container creates a <code>ServletRequest</code> object and passes
 * it as an argument to the servlet's <code>service</code> method.
 * <p>
 * A <code>ServletRequest</code> object provides data including
 * parameter name and values, attributes, and an input stream.
 * Interfaces that extend <code>ServletRequest</code> can provide
 * additional protocol-specific data (for example, HTTP data is
 * provided by {@link javax.servlet.http.HttpServletRequest}.
 *
 * @author Various
 * @see javax.servlet.http.HttpServletRequest
 */
public interface ServletRequest {

    /**
     * Returns the value of the named attribute as an <code>Object</code>,
     * or <code>null</code> if no attribute of the given name exists.
     * <p>
     * Attributes can be set two ways. The servlet container may set
     * attributes to make available custom information about a request.
     * For example, for requests made using HTTPS, the attribute
     * <code>javax.servlet.request.X509Certificate</code> can be used to
     * retrieve information on the certificate of the client. Attributes
     * can also be set programatically using
     * {@link ServletRequest#setAttribute}. This allows information to be
     * embedded into a request before a {@link RequestDispatcher} call.
     * <p>
     * Attribute names should follow the same conventions as package
     * names. This specification reserves names matching <code>java.*</code>,
     * <code>javax.*</code>, and <code>sun.*</code>.
     *
     * @param name a <code>String</code> specifying the name of the attribute
     * @return an <code>Object</code> containing the value of the attribute,
     *         or <code>null</code> if the attribute does not exist
     */
    Object getAttribute(String name);

    /**
     * Returns an <code>Enumeration</code> containing the
     * names of the attributes available to this request.
     * This method returns an empty <code>Enumeration</code>
     * if the request has no attributes available to it.
     *
     * @return an <code>Enumeration</code> of strings containing the names
     *         of the request's attributes
     */
    Enumeration<String> getAttributeNames();

    /**
     * Returns the name of the character encoding used in the body of this
     * request. This method returns <code>null</code> if no request encoding
     * character encoding has been specified. The following methods for
     * specifying the request character encoding are consulted, in decreasing
     * order of priority: per request, per web app (using
     * {@link ServletContext#setRequestCharacterEncoding}, deployment
     * descriptor), and per container (for all web applications deployed in
     * that container, using vendor specific configuration).
     *
     * @return a <code>String</code> containing the name of the character
     *         encoding, or <code>null</code> if the request does not specify a
     *         character encoding
     */
    String getCharacterEncoding();

    /**
     * Overrides the name of the character encoding used in the body of this
     * request. This method must be called prior to reading request parameters
     * or reading input using getReader(). Otherwise, it has no effect.
     *
     * @param env <code>String</code> containing the name of
     *        the character encoding.
     * @throws UnsupportedEncodingException if this ServletRequest is still
     *         in a state where a character encoding may be set,
     *         but the specified encoding is invalid
     */
    void setCharacterEncoding(String env) throws UnsupportedEncodingException;

    /**
     * Returns the length, in bytes, of the request body and made available by
     * the input stream, or -1 if the length is not known ir is greater than
     * Integer.MAX_VALUE. For HTTP servlets,
     * same as the value of the CGI variable CONTENT_LENGTH.
     *
     * @return an integer containing the length of the request body or -1 if
     *         the length is not known or is greater than Integer.MAX_VALUE.
     */
    int getContentLength();

    /**
     * Returns the length, in bytes, of the request body and made available by
     * the input stream, or -1 if the length is not known. For HTTP servlets,
     * same as the value of the CGI variable CONTENT_LENGTH.
     *
     * @return a long containing the length of the request body or -1L if
     *         the length is not known
     * @since Servlet 3.1
     */
    long getContentLengthLong();

    /**
     * Returns the MIME type of the body of the request, or
     * <code>null</code> if the type is not known. For HTTP servlets,
     * same as the value of the CGI variable CONTENT_TYPE.
     *
     * @return a <code>String</code> containing the name of the MIME type
     *         of the request, or null if the type is not known
     */
    String getContentType();

    /**
     * Returns the value of a request parameter as a <code>String</code>,
     * or <code>null</code> if the parameter does not exist. Request parameters
     * are extra information sent with the request. For HTTP servlets,
     * parameters are contained in the query string or posted form data.
     * <p>
     * You should only use this method when you are sure the
     * parameter has only one value. If the parameter might have
     * more than one value, use {@link #getParameterValues}.
     * <p>
     * If you use this method with a multivalued
     * parameter, the value returned is equal to the first value
     * in the array returned by <code>getParameterValues</code>.
     * <p>
     * If the parameter data was sent in the request body, such as occurs
     * with an HTTP POST request, then reading the body directly via {@link
     * #getInputStream} or {@link #getReader} can interfere
     * with the execution of this method.
     *
     * @param name a <code>String</code> specifying the name of the parameter
     * @return a <code>String</code> representing the single value of
     *         the parameter
     * @see #getParameterValues
     */
    String getParameter(String name);

    /**
     * Returns an <code>Enumeration</code> of <code>String</code>
     * objects containing the names of the parameters contained
     * in this request. If the request has
     * no parameters, the method returns an empty <code>Enumeration</code>.
     *
     * @return an <code>Enumeration</code> of <code>String</code>
     *         objects, each <code>String</code> containing the name of
     *         a request parameter; or an empty <code>Enumeration</code>
     *         if the request has no parameters
     */
    Enumeration<String> getParameterNames();

    /**
     * Returns an array of <code>String</code> objects containing
     * all of the values the given request parameter has, or
     * <code>null</code> if the parameter does not exist.
     * <p>
     * If the parameter has a single value, the array has a length
     * of 1.
     *
     * @param name a <code>String</code> containing the name of
     *        the parameter whose value is requested
     * @return an array of <code>String</code> objects
     *         containing the parameter's values
     * @see #getParameter
     */
    String[] getParameterValues(String name);

    /**
     * Returns a java.util.Map of the parameters of this request.
     * <p>
     * Request parameters are extra information sent with the request.
     * For HTTP servlets, parameters are contained in the query string or
     * posted form data.
     *
     * @return an immutable java.util.Map containing parameter names as
     *         keys and parameter values as map values. The keys in the parameter
     *         map are of type String. The values in the parameter map are of type
     *         String array.
     */
    Map<String, String[]> getParameterMap();

    /**
     * Returns the name and version of the protocol the request uses
     * in the form <i>protocol/majorVersion.minorVersion</i>, for
     * example, HTTP/1.1. For HTTP servlets, the value
     * returned is the same as the value of the CGI variable
     * <code>SERVER_PROTOCOL</code>.
     *
     * @return a <code>String</code> containing the protocol
     *         name and version number
     */
    String getProtocol();

    /**
     * Returns the name of the scheme used to make this request,
     * for example,
     * <code>http</code>, <code>https</code>, or <code>ftp</code>.
     * Different schemes have different rules for constructing URLs,
     * as noted in RFC 1738.
     *
     * @return a <code>String</code> containing the name
     *         of the scheme used to make this request
     */
    String getScheme();

    /**
     * Returns the host name of the server to which the request was sent.
     * It is the value of the part before ":" in the <code>Host</code>
     * header value, if any, or the resolved server name, or the server IP
     * address.
     *
     * @return a <code>String</code> containing the name of the server
     */
    String getServerName();

    /**
     * Returns the port number to which the request was sent.
     * It is the value of the part after ":" in the <code>Host</code>
     * header value, if any, or the server port where the client connection
     * was accepted on.
     *
     * @return an integer specifying the port number
     */
    int getServerPort();

    /**
     * Retrieves the body of the request as character data using
     * a <code>BufferedReader</code>. The reader translates the character
     * data according to the character encoding used on the body.
     * Either this method or {@link #getInputStream} may be called to read the
     * body, not both.
     *
     * @return a <code>BufferedReader</code> containing the body of the request
     * @exception UnsupportedEncodingException if the character set encoding
     *            used is not supported and the text cannot be decoded
     * @exception IllegalStateException if {@link #getInputStream} method
     *            has been called on this request
     * @exception IOException if an input or output exception occurred
     * @see #getInputStream
     */
    BufferedReader getReader() throws IOException;

    /**
     * Returns the Internet Protocol (IP) address of the client
     * or last proxy that sent the request.
     * For HTTP servlets, same as the value of the
     * CGI variable <code>REMOTE_ADDR</code>.
     *
     * @return a <code>String</code> containing the
     *         IP address of the client that sent the request
     */
    String getRemoteAddr();

    /**
     * Returns the fully qualified name of the client
     * or the last proxy that sent the request.
     * If the engine cannot or chooses not to resolve the hostname
     * (to improve performance), this method returns the dotted-string form of
     * the IP address. For HTTP servlets, same as the value of the CGI variable
     * <code>REMOTE_HOST</code>.
     *
     * @return a <code>String</code> containing the fully
     *         qualified name of the client
     */
    String getRemoteHost();

    /**
     * Stores an attribute in this request.
     * Attributes are reset between requests. This method is most
     * often used in conjunction with {@link RequestDispatcher}.
     * <p>
     * Attribute names should follow the same conventions as
     * package names. Names beginning with <code>java.*</code>,
     * <code>javax.*</code>, and <code>com.sun.*</code>, are
     * reserved for use by Sun Microsystems.
     * <br>
     * If the object passed in is null, the effect is the same as
     * calling {@link #removeAttribute}.
     * <br>
     * It is warned that when the request is dispatched from the
     * servlet resides in a different web application by
     * <code>RequestDispatcher</code>, the object set by this method
     * may not be correctly retrieved in the caller servlet.
     *
     * @param name a <code>String</code> specifying
     *        the name of the attribute
     * @param o the <code>Object</code> to be stored
     */
    void setAttribute(String name, Object o);

    /**
     * Removes an attribute from this request. This method is not
     * generally needed as attributes only persist as long as the request
     * is being handled.
     * <p>
     * Attribute names should follow the same conventions as
     * package names. Names beginning with <code>java.*</code>,
     * <code>javax.*</code>, and <code>com.sun.*</code>, are
     * reserved for use by Sun Microsystems.
     *
     * @param name a <code>String</code> specifying
     *        the name of the attribute to remove
     */
    void removeAttribute(String name);

    /**
     * Returns the preferred <code>Locale</code> that the client will
     * accept content in, based on the Accept-Language header.
     * If the client request doesn't provide an Accept-Language header,
     * this method returns the default locale for the server.
     *
     * @return the preferred <code>Locale</code> for the client
     */
    Locale getLocale();

    /**
     * Returns an <code>Enumeration</code> of <code>Locale</code> objects
     * indicating, in decreasing order starting with the preferred locale, the
     * locales that are acceptable to the client based on the Accept-Language
     * header.
     * If the client request doesn't provide an Accept-Language header,
     * this method returns an <code>Enumeration</code> containing one
     * <code>Locale</code>, the default locale for the server.
     *
     * @return an <code>Enumeration</code> of preferred
     *         <code>Locale</code> objects for the client
     */
    Enumeration<Locale> getLocales();

    /**
     * Returns a boolean indicating whether this request was made using a
     * secure channel, such as HTTPS.
     *
     * @return a boolean indicating if the request was made using a
     *         secure channel
     */
    boolean isSecure();

    /**
     * Returns the Internet Protocol (IP) source port of the client
     * or last proxy that sent the request.
     *
     * @return an integer specifying the port number
     * @since Servlet 2.4
     */
    int getRemotePort();

    /**
     * Returns the host name of the Internet Protocol (IP) interface on
     * which the request was received.
     *
     * @return a <code>String</code> containing the host
     *         name of the IP on which the request was received.
     * @since Servlet 2.4
     */
    String getLocalName();

    /**
     * Returns the Internet Protocol (IP) address of the interface on
     * which the request was received.
     *
     * @return a <code>String</code> containing the
     *         IP address on which the request was received.
     * @since Servlet 2.4
     */
    String getLocalAddr();

    /**
     * Returns the Internet Protocol (IP) port number of the interface
     * on which the request was received.
     *
     * @return an integer specifying the port number
     * @since Servlet 2.4
     */
    int getLocalPort();

    //    /**
    //     * Gets the servlet context to which this ServletRequest was last
    //     * dispatched.
    //     *
    //     * @return the servlet context to which this ServletRequest was last
    //     *         dispatched
    //     * @since Servlet 3.0
    //     */
    //    ServletContext getServletContext();

    /**
     * Checks if this request has been put into asynchronous mode.
     * <p>
     * A ServletRequest is put into asynchronous mode by calling
     * {@link #startAsync} or
     * {@link #startAsync(ServletRequest,ServletResponse)} on it.
     * <p>
     * This method returns <tt>false</tt> if this request was
     * put into asynchronous mode, but has since been dispatched using
     * one of the {@link AsyncContext#dispatch} methods or released
     * from asynchronous mode via a call to {@link AsyncContext#complete}.
     *
     * @return true if this request has been put into asynchronous mode,
     *         false otherwise
     * @since Servlet 3.0
     */
    boolean isAsyncStarted();

    /**
     * Checks if this request supports asynchronous operation.
     * <p>
     * Asynchronous operation is disabled for this request if this request
     * is within the scope of a filter or servlet that has not been annotated
     * or flagged in the deployment descriptor as being able to support
     * asynchronous handling.
     *
     * @return true if this request supports asynchronous operation, false
     *         otherwise
     * @since Servlet 3.0
     */
    boolean isAsyncSupported();

    //    /**
    //     * Gets the AsyncContext that was created or reinitialized by the
    //     * most recent invocation of {@link #startAsync} or
    //     * {@link #startAsync(ServletRequest,ServletResponse)} on this request.
    //     *
    //     * @return the AsyncContext that was created or reinitialized by the
    //     *         most recent invocation of {@link #startAsync} or
    //     *         {@link #startAsync(ServletRequest,ServletResponse)} on
    //     *         this request
    //     * @throws IllegalStateException if this request has not been put
    //     *         into asynchronous mode, i.e., if neither {@link #startAsync} nor
    //     *         {@link #startAsync(ServletRequest,ServletResponse)} has been called
    //     * @since Servlet 3.0
    //     */
    //    AsyncContext getAsyncContext();

    //    /**
    //     * Gets the dispatcher type of this request.
    //     * <p>
    //     * The dispatcher type of a request is used by the container
    //     * to select the filters that need to be applied to the request:
    //     * Only filters with matching dispatcher type and url patterns will
    //     * be applied.
    //     * <p>
    //     * Allowing a filter that has been configured for multiple
    //     * dispatcher types to query a request for its dispatcher type
    //     * allows the filter to process the request differently depending on
    //     * its dispatcher type.
    //     * <p>
    //     * The initial dispatcher type of a request is defined as
    //     * <code>DispatcherType.REQUEST</code>. The dispatcher type of a request
    //     * dispatched via {@link RequestDispatcher#forward(ServletRequest,
    //     * ServletResponse)} or {@link RequestDispatcher#include(ServletRequest,
    //     * ServletResponse)} is given as <code>DispatcherType.FORWARD</code> or
    //     * <code>DispatcherType.INCLUDE</code>, respectively, while the
    //     * dispatcher type of an asynchronous request dispatched via
    //     * one of the {@link AsyncContext#dispatch} methods is given as
    //     * <code>DispatcherType.ASYNC</code>. Finally, the dispatcher type of a
    //     * request dispatched to an error page by the container's error handling
    //     * mechanism is given as <code>DispatcherType.ERROR</code>.
    //     *
    //     * @return the dispatcher type of this request
    //     * @see DispatcherType
    //     * @since Servlet 3.0
    //     */
    //    DispatcherType getDispatcherType();

}
